SetThreadStateEndCritical

SetThreadStateEndCritical
Header:	Threads.h		Carbon status:	Supported

Changes the state of the current thread and exits that threadís critical section at the same time.

OSErr SetThreadStateEndCritical (
    ThreadID threadToSet, 
    ThreadState newState, 
    ThreadID suggestedThread
);

threadToSet: The thread ID of the thread whose state is to be changed.
newState: The new state for the thread. You can specify ready to execute (kThreadReadyState), stopped (kStoppedThreadState) or executing (kRunningThreadState).
suggestedThread: The thread ID of the next thread to run. You specify this thread if you are changing the state of the currently executing thread to stopped or ready to run. Pass kNoThreadID if you do not want to specify a particular thread to run next. In this case, the Thread Manager schedules the next available thread to run.

function result: A result code.

DISCUSSION

The SetThreadStateEndCritical function does in one step the same thing that ThreadEndCritical and SetThreadState function do in two steps.

Historically, the primary purpose of the SetThreadStateEndCritical function was to close the scheduling window at the end of a critical section. A preemptive thread that was waiting while the critical section of code was executing could begin executing before you changed the state of the current thread to stopped with the SetThreadState function. Obviously, because the Thread Manager no longer supports preemptive threads, this function is no longer necessary to close the scheduling window, but you can still use it to change the state of a thread and exit a critical section in one step instead of two.

When you change the state of the currently executing thread, the Thread Manager schedules the thread you specify with the suggestedThread parameter. If this thread is unavailable or if you pass kNoThreadID, the Thread Manager schedules the next available thread.

To mark a section of code as critical, use the ThreadBeginCritical and the ThreadEndCritical functions.

To change the state of any thread, use the SetThreadState function.

AVAILABILITY

Supported in Carbon. Available in CarbonLib 1.0 and later when ThreadsLib 1.0 or later is installed. Exported by CarbonLib 1.0 and later and by ThreadsLib 1.0 and later.